
\chapter{Program structure}

\label{chapter:program}

This chapter provides information about organizing, loading, and
compiling programs.

\section{Environment structure}


Lexical environments in {\bf T} are hierarchically arranged.  Variable
bindings are inherited from outer (superior) contours to inner
(inferior) ones.  At the top of the hierarchy is a
root environment, which has no bindings in it.  Inferior to that is a
standard environment which has bindings for all standard system
variables, for example, {\tt CAR} and {\tt +}.  (See
section \ref{section:standardEnvironment}.)
Inferior to the standard environment are environments into which programs
have been or are to be loaded.  In the standard environment, the variable
{\tt STANDARD-ENV} is bound to the standard environment itself.

When a {\bf T} system starts up, it sets up an initial environment
configuration which has one environment inferior to the standard
environment, called the \iix{user environment}.  The variable
{\tt USER-ENV} is bound in the standard
environment to the user environment.  The user environment has
no variable bindings in it at first; however, the initial
read-eval-print loop (section \ref{section:repl}) is started in this
environment, so that if no other provision is made, user global variable
(i.e. definitions) will be made in the user environment.

In {\bf T} 3.1, there is another environment called the
\iix{implementation environment} (page \pageref{T-IMPLEMENTATION-ENV}).
This is the value of {\tt T-IMPLEMENTATION-ENV} in the standard
environment.  The implementation environment is not inferior to the
standard environment, but instead is inferior to the root.

In {\bf {\bf T} 3.0}, the initial locales look like:

\begin{verse}
\begin{verbatim}

                                 <root>
                                /  |  \
                              /    |    \
                            /      |      \
                          /        |        \
                        /          |          \
       t-implementation-env   standard-env   scheme-env
                               /   |   \
                             /     |     \
                           /       |       \
                     user-env  orbit-env  scheme-internal-env

\end{verbatim}
\end{verse}

\begin{description}

\item[{{\tt <root>}}]  The {\tt <root>} locale is the conceptual root of the
        locale tree.  It does not actually exist.
        The {\tt <root>} locale is empty, it contains no variable bindings.

\item[{{\tt t-implementation-env}}] The {\mbox {\tt t-implementation-env}} is the
        environment which contains the system internals.

\item[{{\tt standard-env}}]  The {\mbox {\tt standard-env}} is the environment
        defined by the T manual.

\item[{{\tt user-env}}]  The {\mbox {\tt user-env}} is the default environment for
        the {\mbox {\tt read-eval-print-loop}} on system startup.

\item[{{\tt orbit-env}}]  The {\mbox {\tt orbit-env}} is the environment which
        contains the internals of the {\sc orbit} compiler.

\item[{{\tt scheme-internal-env}}]  The {\mbox {\tt scheme-internal-env}} contains
        the system internals for the Scheme environment.

\item[{{\tt scheme-env}}]  The {\mbox {\tt scheme-env}} is the environment defined
        by Revised3 Report on Scheme.

\end{description}


Empty environments may be created using {\tt MAKE-EMPTY-LOCALE} (page
\pageref{MAKE-EMPTY-LOCALE}).  For example:
\begin{codexenv}
(DEFINE *ALMOST-USELESS-ENV* (MAKE-EMPTY-LOCALE '*ALMOST-USELESS-ENV*)) \\
(*DEFINE *ALMOST-USELESS-ENV* '+ +) \\
(*DEFINE *ALMOST-USELESS-ENV* '- -) \\
(EVAL '(+ 5 (- 21 13)) *ALMOST-USELESS-ENV*)  $\Longrightarrow$\   13
\end{codexenv}

\index{STANDARD-ENV@{\tt STANDARD-ENV}}
{\mbox {\tt STANDARD-ENV $\longrightarrow$\  {\it locale\/}}}
\hfill  

\label{STANDARD-ENV}
\index{standard environment}
\begin{inset}{}
The value of {\tt STANDARD-ENV} is an environment (a locale)
in which all system variables have appropriate values,
as described in this manual.  That is, it is a {\it standard environment\/}
in the sense of section \ref{section:standardEnvironment}.
\end{inset} 

\label{user-env}
\index{USER-ENV@{\tt USER-ENV}}
{\mbox {\tt USER-ENV $\longrightarrow$\  {\it locale\/}}}
\hfill  

\label{USER-ENV}
\begin{inset}{}
The value of {\tt USER-ENV} is an environment (a locale)
inferior to {\tt STANDARD-ENV}.
It is provided by a {\bf T} implementation as an environment in which a user
may evaluate expressions and write programs.
Other evaluation environments may be created inferior
to {\tt STANDARD-ENV}, however, with {\tt MAKE-LOCALE} (page
\pageref{MAKE-LOCALE}).
\end{inset}

\section{Source files}


{\bf T} programs are usually represented by collections of one or more text
files resident in a file system.  Text files containing {\bf T} programs
are called \iix{source files}.

A source file consists of a sequence of (external representations of)
{\bf T} expressions.  Source files may be {\it loaded\/} into a {\bf T} environment.
When a file is loaded, the expressions in the file are evaluated.
Typically, this means that useful side-effects, such as procedure
definitions, occur which then make the program available in that {\bf T}
environment.
\index{loading}

A compilation (semantic analysis) step must occur either as a file
is being loaded, or prior to loading the file.  In the former case,
compilation is typically performed by a compiler such as the
``standard compiler'' (page \pageref{STANDARD-COMPILER}) which itself runs
relatively quickly and produces intermediate code which must then
be interpreted.  In the latter case, an auxiliary file known as an
{\it object file\/} is involved; the compilation step need only be performed
once, even if the file is to be loaded many times.  (The term {\it object
file\/} is completely unrelated to the term {\it object.\/})

A {\it file compiler\/} (such as {\sc orbit}; see section \ref{section:orbit}) takes
a source file as input and produces an object file as output.  The
object file may then be loaded in lieu of the source file, with
the same effect.

\begin{inset}{Note:}
In the current implementation, the standard compiler cannot be used
as a file compiler, and {\sc orbit} cannot be used as an ``on-the-fly''
compiler.  In principle, the two dimensions of compiler and compilation
mode are orthogonal:  it should be possible to use either compiler
in either manner.  In practice, this is not the case, but it turns out
not to be too much of a problem.
\end{inset}

\section{File syntax}


The first form in a source file must be a list whose car is the
symbol {\tt HERALD}.  This form is not an expression, but
rather is part of the syntax of the file.
It provides information relevant to programs which operate on the
source file (such as readers, compilers, and loaders).
The syntax of a {\tt HERALD}-form is as follows:
\begin{codexenv}
(HERALD {\it identification\/} . {\it items\/})
\end{codexenv}
{\it Identification\/} should be either {\tt ()} or a symbol identifying
the file (usually the same as the root of the name of the file).
It is for documentary purposes only.

{\it Items\/} is a sequence of lists.  Each {\it item\/} should be
a list beginning with a valid keyword symbol, as described below.

Example:
{\tt \begin{tabbing}
(HERALD \= FACT \+ \\
        (READ-TABLE *MATH-READ-TABLE*) \\
        (ENV T (MATH MATHMACROS)))
\end{tabbing}}

\index{READ-TABLE@{\tt READ-TABLE}}
{\mbox {\tt (READ-TABLE {\it expression\/})}}
\hfill Herald item

\begin{inset}{}
{\it Expression\/} should evaluate to a read table, which is used
in reading the expressions which follow the {\tt HERALD}-form from
the source file.  The environment in which {\it expression\/} is evaluated
depends on the program processing the file (but might be, e.g., the
scratch environment).

If this item is absent, then expressions are read using the
standard read table.
\end{inset} 

\index{SYNTAX-TABLE@{\tt SYNTAX-TABLE}}
{\mbox {\tt (SYNTAX-TABLE {\it expression\/})}}
\hfill Herald item

\begin{inset}{}
{\it Expression\/} should evaluate to a syntax table, which is used
in compiling (evaluating) the expressions in the source file.
The environment in which {\it expression\/} is evaluated
depends on the program processing the file (but might be, e.g., the
scratch environment).

If this item is absent, then expressions are compiled according
to an appropriate syntax table: the syntax table associated with the
locale into which the file is being loaded, if the file is being loaded,
or the current value of {\tt (TC-SYNTAX-TABLE)} (see below), if the
file is being compiled using {\sc orbit} .
\end{inset} 


\index{ENV@{\tt ENV}}
{\mbox {\tt (ENV {\it support-env-name\/} . {\it filespecs\/})}}
\hfill Herald item

\label{ENV}
\begin{inset}{}
Specifies a support (early binding) environment for compiling the file.
The support environment consists of the support environment named
by {\it support-env-name\/}, augmented by information obtained from
support files named by {\it filespecs\/}.

If this item is absent, then the standard support environment,
whose name is {\tt T}, is used.  The ability to create and name other
support environments is not yet documented.
\end{inset} 

\section{Loading files}



\index{LOAD@{\tt LOAD}}
{\mbox {\tt (LOAD {\it filespec\/} {\it environment\/}) $\longrightarrow$\  {\it undefined\/}}}
\hfill  

\begin{inset}{}
Loads the file named by {\it filespec\/}.  If the file is a source file,
then each expression in the file is compiled (with the standard
compiler) and run in {\it environment\/}.  If the file is an object file,
as produced by TC, then the compiled object code is simply run in
{\it environment\/}.

If no explicit file type is given in the {\it filespec\/}, then {\tt LOAD}
will load either an object file (file type {\tt BIN}), if one exists,
or a source file (file type {\tt T}) otherwise.
\end{inset} 

\index{LOAD-OUT-OF-DATE-ACTION@{\tt LOAD-OUT-OF-DATE-ACTION}}
{\mbox {\tt (LOAD-OUT-OF-DATE-ACTION) $\longrightarrow$\  {\it symbol}}}
\hfill 

\begin{inset}{}
{\mbox {\tt LOAD-OUT-OF-DATE-ACTION}} is a switch that controls what the loader does
with a filespec without an extension.  The options are:

\begin{description}
\item[{binary}] load the object file.
\item[{source}] load the source file.
\item[{newer}]  load the most recent of object and source files.
\item[{recompile}] recompile the file if the source is newer than the object file.
\item[{warn}] give a warning if the source is newer than the object file.
\item[{query}] offer to recompile if the source is newer than the object
file.
\end{description}

The default is {\mbox {\tt WARN}}.
\end{inset}



\section{File compilation}

\label{section:orbit}

In addition to the standard compiler invoked when {\tt EVAL} or
{\tt LOAD} is called,
{\bf T} provides an optimizing compiler.  This compiler,
known as {\sc orbit}, trades compilation
speed for execution speed: {\tt STANDARD-COMPILER} tries to compile quickly,
while {\sc orbit} tries to generate executable code which will run
fast.
\index{compilers}
\index{early bindings}

To help produce more efficient code, {\sc orbit} makes assumptions about the
values that some variables will have at run-time.  These assumptions
are called \iix{early bindings.}  For example, it will ordinarily assume
that the variable {\tt PAIR?} will have the standard {\tt PAIR?} predicate
as its top-level value.  This means that if an object file produced
under this assumption is loaded into a lexical environment where this
is not the case, then calls to {\tt PAIR?} will not execute the same as
they would if the source file had been loaded.

Early bindings are obtained from \iix{support environments}.
The support environment to be used in compiling a file may be
specified by an {\tt ENV} clause in the file's
header.  (See page \pageref{ENV}.)
A support environment may contain user-defined integrable procedure
and constant definitions.

Besides early binding, another source of improved efficiency is a
difference in the handling of undefined effects (that is, run-time
program errors).
\index{undefined effects}
When code compiled using the standard compiler incurs an error, an
error is signalled, and the error system is entered, giving the user
an opportunity to debug the problem at the point where it occurs.
Code compiled using {\sc orbit} has less error-checking, so the effect of an
error may go unnoticed until long after the error occurred, or a
secondary error of an obscure or unexpected kind will occur.

{\sc orbit} can be invoked from within {\bf T} by using the following
functions.

\index{COMPILE-FILE@{\tt COMPILE-FILE}}
{\mbox {\tt (COMPILE-FILE {\it filespec\/}) $\longrightarrow$\  {\it undefined\/}}}
\hfill  

\label{COMPILE-FILE}
\begin{inset}{}
Alternatively {\tt COMFILE}\index{COMFILE@{\tt COMFILE}}.
To compile a source file, say, {\tt fact.t}, use
{\mbox {\tt (COMPILE-FILE "fact")}}.  {\sc orbit} writes three output files, all having the
same file name as the
{\bf T} source, and distinguished by extension:

\begin{itemize}
\item[{}]The \iix{noise file} is a transcript of what {\sc orbit} wrote to the terminal
in the course of the compilation.  {\sc orbit} also writes some additional
statistics and cross-referencing information to noise files.

\item[{}]The \iix{support file} contains early binding information useful
for compiling other files with {\sc orbit}.  See the {\tt ENV} file header
clause, page \pageref{ENV}

\item[{}]The \iix{object file} contains the native code for the target
machine that can be loaded into {\bf T}.
\end{itemize}

The file extensions for the output files depend on the target architecture.
For MC68000, VAX, and Encore, the extensions are as follows:
\begin{center}
\begin{tabular}{llll}
Architecture &Support     &Noise       &Object \\
68000        &{\tt .mi}    &{\tt .mn}    &{\tt .mo} \\
VAX11        &{\tt .vi}    &{\tt .vn}    &{\tt .vo} \\
Encore       &{\tt .ni}    &{\tt .nn}    &{\tt .no} \\
\end{tabular}
\end{center}
\end{inset}

\index{ORBIT@{\tt ORBIT}}
{\mbox {\tt (ORBIT {\it expression . locale}) $\longrightarrow$\  {\it undefined}}}
\hfill 

\begin{inset}{}
{\mbox {\tt ORBIT}} does expression at a time compilation, e.g.
{\mbox {{\tt (ORBIT (DEFINE (F X) (+ X 1))}}}')
will cause the expression to be compiled and loaded into the
(REPL-ENV).
\end{inset}

\index{CL@{\tt CL}}
{\mbox {\tt (CL {\it expression}) $\longrightarrow$\  {\it undefined}}}
\hfill 

{\mbox {\tt (CL {\it expression\/})}} prints out assembly code for {\it expression\/}.

\index{TC-SYNTAX-TABLE@{\tt TC-SYNTAX-TABLE}}
{\mbox {\tt (TC-SYNTAX-TABLE) $\longrightarrow$\  {\it syntax-table\/}}}
\hfill Settable

\begin{inset}{}
This is the basic syntax table from which {\sc orbit}
obtains macro definitions.  {\sc orbit} obtains additional macro
definitions from the support environment set up by an {\tt (ENV \ldots\ )}
{\tt HERALD} clause.  Its default value is the syntax table of the
user environment.
\begin{inset}{Warning:}
This may change in the future.
\end{inset}
\end{inset} 

\index{ENV-FOR-SYNTAX-DEFINITION@{\tt ENV-FOR-SYNTAX-DEFINITION}}
{\mbox {\tt (ENV-FOR-SYNTAX-DEFINITION {\it syntax-table\/}) $\longrightarrow$\  {\it environment\/}}}
\hfill Settable

\label{ENV-FOR-SYNTAX-DEFINITION}
\begin{inset}{}
The environment in which macro                             
definition bodies themselves are evaluated, either as a result of
encountering a {\tt DEFINE-LOCAL-SYNTAX} or {\tt LET-SYNTAX}
expression, or by loading macro definitions from a
support file.
{\sc orbit} evaluates syntax-descriptors in the
{\mbox {\tt ENV-FOR-SYNTAX-DEFINITION}} associated with the syntax
table from which the descriptor was obtained, e.g.
for {\mbox {\tt (tc-syntax-table)}}, the default environment is {\tt USER-ENV}.
\end{inset} 


